This is one of a collection of interface libraries that can be used to interact
with the Amazon S3 system in a number of different languages.  They each expose
two main interface classes, AWSAuthConnection and QueryStringAuthGenerator.
The first actually performs all the operations using the appropriate libraries
for the language, including header signing.  The second,
QueryStringAuthGenerator, has the same interface, but instead of performing
the operation, this class will return urls with the right query string
authentication parameters set.


Basic Operations:

object requests:

GetResponse get(bucketName, keyName) - retrieves an object
GetResponse getACL(bucketName, keyName) - returns the xml acl doc
Response put(bucketName, keyName, object) - writes an object
Response putACL(bucketName, keyName, aclXMLDoc) - sets the xml acl doc
Response delete(bucketName, keyName) - deletes an object

bucket requests:

Response createBucket(bucketName, location) - creates a bucket
ListResponse listBucket(bucketName) - lists a bucket's contents
LocationResponse getBucketLocation(bucketName) - return the location-constraint of this bucket
GetResponse getBucketACL(bucketName) - returns the xml representation of this bucket's access control list
Response putBucketAcl(bucketName, aclXMLDoc) - sets xml representation of the bucket acl
Response deleteBucket(bucketName) - delete an empty bucket
GetResponse getBucketLogging(bucketName) - returns the xml representation of this bucket's access logging configuration
Response putBucketLogging(bucketName, loggingXMLDoc) - sets the xml representation of the bucket logging configuration

ListAllMyBucketsResponse listAllMyBuckets() - returns a list of all buckets owned by this AWS Access Key Id



Dependencies:

None, beyond the standard libraries.


Notes:

Please note that this uses the public domain iHarder.net Base64 library.  For updates to that library,
see http://iharder.sourceforge.net/current/java/base64/ .

If your bucket name contains periods, you will need to use a non-HTTPS connection as the SSL certificate
presented by s3.amazonaws.com will not match if you do.

Limitations:

One of the main limitations of these sample AWSAuthConnection implementations
is that the interfaces are not streaming.  This means that you have to pass the
data in as a string or as a byte array and the operation returns a string or a
byte array back.  This is conceptually simpler, and fine for smaller objects,
but large objects, say a couple megabytes or greater, will show poor
performance, since everything is being passed around in memory.  More
sophisticated libraries would pass streams in and out, and would only read the
data on-demand, rather than storing it all in memory (S3 itself would have no
problem with such streaming applications).  Another upshot of this is that the
interfaces are all blocking---that is, you cannot look at the data until all of
it has downloaded.  Again, this is fine for smaller objects, but unacceptable
for larger ones.

These libraries have nearly non-existent error handling.  All errors from lower
libraries are simply passed up.  The response code in the connection object needs
to be checked after each request to verify whether the request succeeded.

Only the java library has proper handling for repeated headers.  The others
assume that each header will have only one value.

It is our intention that these libraries act as a starting point for future
development.  They are meant to show off the various operations and provide an
example of how to negotiate the authentication process.



This software code is made available "AS IS" without warranties of any        
kind.  You may copy, display, modify and redistribute the software            
code either by itself or as incorporated into your code; provided that        
you do not remove any proprietary notices.  Your use of this software         
code is at your own risk and you waive any claim against Amazon               
Digital Services, Inc. or its affiliates with respect to your use of          
this software code. (c) 2006 Amazon Digital Services, Inc. or its             
affiliates.          
